feature/SOF-8034 Fix: preserve the input crystal in build metadata - #297

Closes the SOF-8034 defect: builders recorded a conventionalized copy of the material instead of the one passed in, so a Total Energy job run on a primitive cell was unreachable from a slab built from it. create_slab(Ni_primitive, (0,0,1), 3) recorded ad81bcd8… (conventional Ni4) instead of the input 18d50c5c….

What changed

The input crystal is now stored untransformed, and conventionalization moves to build time — where the use_conventional_cell flag already lived.

• CrystalLatticePlanesBuilder._generate applies the transform
• SlabConfiguration.from_parameters forwards the flag instead of rebinding material
• four helpers (zsl, commensurate, both grain boundaries) stop conventionalizing before building their configuration
• create_atomic_layers pins the flag False, preserving its existing behaviour

hash/scaledHash are computed fields and _id rides on the stored object, so no round-trip helper was needed — the ticket's root cause 3 turned out to be unnecessary rather than deferred.

Two named exclusions — the criterion is not "every builder"

• twisted — TwistedNanoribbonsInterfaceAnalyzer reads atomic_layers.crystal as geometry and never calls the builder, so the transform cannot reach it there. twisted/helpers.py is deliberately unchanged; an earlier revision of this branch did change it and silently collapsed use_conventional_cell=True from 8 atoms to 1. Guarded by a test now.
• heterostructure — records metadata.build == [], on main and after this change alike. Nothing to inherit. Separate ticket.

Consequences

• Configurations saved before this change do not round-trip. from_parameters never forwarded the flag, so every stored configuration reads "use_conventional_cell": true — including slabs built from the primitive cell. _generate used to ignore it and now honors it, so those rebuild conventionalized (measured: 3 atoms a=2.479 → 12 atoms a=3.5058). Not fixable — a stale true is indistinguishable from a real one. Pinned by a test. Rebuild such a slab from its crystal, not from its metadata.
• Site ordering can differ on materials where conventionalization is not order-idempotent (TiN, Hf2O-MCL, Si-primitivized). Same hash, same lattice, same atom set — verified identical for TiN. This is base's redundant conventionalize² becoming conventionalize¹, not damage.
• Newly built slabs record a different crystal hash than older ones; ~6 in-repo consumers of atomic_layers.crystal now see the input cell.

Verification

• 313 passed (was 303 on main; +10 new) with zero existing hash fixtures edited — that was the stop condition for geometry movement
• New tests/py/unit/test_build_metadata_records_input_crystal.py: 10 passed, and 6 failed / 3 passed against unmodified source
• Swept every touched helper base-vs-patched across both flag values, 14 builds, comparing hash and site ordering: 13/14 byte-identical
• surface_energy.feature passes end to end against a wheel built from this branch, served through a local JupyterLite (verified by its access log)
• Three grounded tb-reviewer rounds; round 3 approved

Manual checks

Merging accepts anything left unticked.

• The flag now means something. ideal_crystal/builder.py:41 and analyze/interface/twisted_nanoribbons.py:48 pass use_conventional_cell=False. Confirm their build metadata serializes false, not the schema default true.
• Interface naming. interface/base/builder.py:105-106 derives the name from a reduced formula. Primitive Ni and Ni4 both reduce to Ni — confirm one built ZSL interface's name is byte-identical before and after.
• lattice.type on the recorded crystal is now the input's. If the input fixture itself carries TRI for a cubic cell, that is upstream, not this task.

Not done here

calculate_interfacial_distance_from_rdf's isinstance(x, SlabConfiguration) branch returns 2.35 Å where main returned 3.85 Å for primitive Si. It has no caller in made, api-examples or the notebooks, and 2.35 Å is what its docstring promises — recorded as a finding, either delete the dead branch or give it a caller and a test.

🤖 Generated with Claude Code